看完了別人寫的 API 文件範例，身為後端工程師當然也要學會撰寫 API 文件。

這部分我只用過 scribe 套件撰寫，這邊就來介紹此套件的用法。

Scribe 套件介紹

scribe 套件可協助後端工程師輕鬆產生 API 文件，只要在程式碼裡面多加入一些註解，它就可以產生單一頁面 HTML 檔案，且內容可支援中文！

這個套件必須使用 PHP 8.0 以上版本，搭配 Laravel/Lumen/Dingo 使用。

官方文件、產生的 API 文件範例

安裝

// composer 安裝套件
composer require --dev knuckleswtf/scribe

// 發布 config 檔案，產生 scribe.php 檔案
php artisan vendor:publish --tag=scribe-config

題外話 —dev 選項

使用—dev選項將套件加入 composer 時，會將套件加入composer.json 文件的 require-dev 部分，而不是 require 部分。

這是為了區分哪些套件是只限於開發階段使用，哪些套件是正式上線階段，當網站要在正式環境啟用、或是我們將專案放到 AWS / GCP 雲端時，就可以選擇不安裝這些開發時的套件。

發布 API 文件

php artisan scribe:generate

最後一行有網址，當模擬伺服器 php artisan serve 啟用時，就可以點開那個網址看到產生的 API 文件。

這裡記得要把 localhost:8000 改為模擬伺服器正式啟用的域名跟 port 號

以我的案例是 http://localhost:8000/docs 或 http://127.0.0.1:8000/docs 都可以開啟

目前內容還都是空白，要進一步撰寫內容。

API 文件撰寫

回顧昨天的章節，好的 API 文件有幾個區塊，初次撰寫 API 的話建議可先就以下區塊學習：

• API 描述
• 端點和請求(Endpoints and Requests)
• 參數(Parameters)
• 響應(Responses) 與 範例(Examples)
• 身份驗證和授權(Authentication and Authorization)

範例：取得一筆團購資料、標籤撰寫順序

通常，我會將 API 文件寫在 controller 的每個方法前面，因為每個 routes 都會進到 controller 裡面，可以直接在撰寫動作邏輯時一併修改 API 文件內容。

    /**
     * 取得單一筆團購資料
     *
     * @urlParam group_id integer 團購資料的 ID Example:34
     */
    public function showApi(Group $group)
    {
        return GroupResource::make($group);
    }

• API 描述：給這支 API 一個標題
• ＠urlParam 是 url 網址 的參數，以這支 API 來說，http://localhost:8000/group/{group_id} 這裡的 urlParam 就是 group_id

比較特別的是，scribe 使用的 @ 標籤，是透過字串前後順序、Example 字串判別：

@標籤 參數名稱 參數格式 required 備註文字 Example:

範例：新增一筆團購資料、回應檔案

	 /**
     * 新增一筆團購資料
     *
     * 可以在這裡新增詳細說明
     *
     * @bodyParam group_name string required 團購名稱，最小3字元、最大50字元 Example: 好想團購
     * @bodyParam organizer_id int required 發起人 ID
     * @bodyParam close_price int 結團金額，結團金額或結團時間至少要提供一個 Example: 2000
     * @bodyParam close_date date 結團日期，必須大於或等於今日 Example: 2023-10-10
     * @bodyParam allow_insert_product boolean 允許使用者新增產品，可為null
     * @bodyParam status int required 團購狀態，0=未開團、1=開團中、2=結團處理中、3=運送處理中 Example:0
     * @bodyParam group_image image 團購圖片，最大2MB，接受 jpeg, png, jpg, gif 檔案
     *
     * @responseFile responses/GroupStoreApi.json
     */

• @bodyParam 則是 post 請求 body 裡面帶的參數，採用跟上面 @urlParam 一樣的邏輯撰寫
• 有時候 回應的資料沒辦法自己抓到 Postman 的內容，可以自行將 Postman 回傳內容貼入 json 檔案，放置於 storage/responses/ 路徑下，並加入 @responseFile 標籤。

群組標籤

當 API 支數越來越多時，會需要分類以讓使用者更好閱讀，此時可以在Controller 最上層加入群組及次要群組標籤，就會像資料夾一樣分類出來。

注意：群組標籤如果是中文開頭會有些讀不到，需要先使用英文，後面再加入中文

/**
 * @group Group Management 團購管理
 * 團購相關 API 管理
 * @subgroup 團購相關API子群組
 */
class GroupController extends Controller
{
}

提醒需要身份驗證的標籤

如果是需要會員登入、或是帶 token 的 API ，可以用 @authenticated 標籤，就會出現紅色的字樣提醒。

這個標籤不僅可以用在單一 API，也可以在 @group 標籤下使用，這樣群組內的 API 都會被標示出來。

    /**
     * 取得所有團購資料
     *
     * 可用於首頁，排序依照關團時間 ASC 、最後更新時間 DESC 、團購資料 ID ASC
     * 設有分頁功能
     *
     * @authenticated
     *
     */

注意：任何修改都需要重新發布

因為 scribe 套件是透過程式碼重新渲染產生一頁式 HTML 套件，所以有任何修改都需要重新發布

php artisan scribe:generate